Wrap documentation at 100 characters #5635
Conversation
zanieb
added
documentation
|
Note that I prefer it to be unwrapped and for people to use soft-wrap in their editors because the diff is nonsense when you hard-wrap but 🤷♀️ feel like I'm alone in that. |
|
I used the VSCode Rewrap plugin for this, I'd love to hear about alternative tooling as that isn't particularly maintained and I don't love that it split inline code. |
zanieb
force-pushed
the
zb/docs-project-concept
branch
from
a6dcd66
to
94f0ec8
Compare
Yeah diff quality is one of the downsides of hard-wrap. Back in my days as an academic, when collaborating on a paper, we would always try to insert a line break after a sentence. (Although we still hard-wrapped at 80 columns.) This tended to help with diffs but it's difficult to automate. Here's a screenshot of what soft-wrap looks like in my editor:
And here's what it looks like when I open a second window next to it. The text kinda smushes and runs together with no real smarts about where to insert breaks (vim will just happily insert breaks right in the middle of words):
And in particular, one of the very annoying things about soft-wrap, at least in vim, is that it looks like, at a glance, that, for example, "Python does not publish" and "distributions" are on two different lines. And so if your cursor is on "publish," it's easy to be misled that moving down a line should have you land on "distributions." But of course, it doesn't. And so navigating to different parts of the text winds up being really annoying. And finally, compare the above with what hard-wrap looks like:
Now the test is a bit easier to read (for me) even when I have one window stretched across the screen because the text is wrapped at a reasonable point. And moving the cursor around is consistent with the appearance. And words aren't split arbitrarily. This is to some extent a tooling deficiency, but not completely so IMO. This is also largely why I find long lines of code unwieldy as well.
I use |
Same, there's so much noise with the reflowing |
To enforce the 100 character line limit in markdown files introduced in #5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it. I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them. I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though. This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with `npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md`. --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
Basically sick of dealing with mixed formatting here. Going with the number at
uv/.editorconfig
Line 20 in 7c08e61